The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/umich/telecomm/storm100.lzh/BASIC.DOC

Text File | 1993-11-03 | 66.6 KB | 1,934 lines

            Basic language overview

This document assumes you are already familiar with the Basic language. Its
purpose is to explain the special features of Storm Basic.

Storm Basic is a Basic language interpreter with extensions to handle the
serial port, file transfer, and other Storm functions. It does not have
floating point or graphics features.

Variables:

You can only have 128 total variables. There is no fixed limit on the length of
a variable name, as long as it fits on a single line. Upper and lower case ARE
significant in variable names.

You can use the same variable name for an integer, an integer array, a string,
and a string array. e.g. in:

DIM x(10),x$(10)
x = LEN(x$)

there are actually four separate variables.

Math functions:

The usual math operations are supported. e.g. addition, subtraction,
multiplication, division and MOD (modulus function) and the Boolean functions
XOR, NOT, AND and OR. The comparision operators >, <, >=, <= and <> are
supported. In accordance with typical Basic practice, TRUE is -1 and FALSE is 0.

Arrays:

Each element of an array, whether string or integer, requires four bytes of
overhead. The maximum array space available is 64K. That means that the maximum
number of array elements is limited to a combined total of 16384. Arrays can
have one or two dimensions only. Trying to dimension more than two array
dimensions will cause a syntax error.

Memory:

Basic allocates memory as required and releases it when no longer required.
Each Basic string or element of a string array is allocated separately and can
be up to 64K long. The total amount of string memory is limited to
approximately 638K, which should be enough for even the most demanding programs.

The total size of a Basic program is limited only by available memory. However,
the total number of lines in a program must not exceed 64K.

Labels

There are no line numbers in Storm Basic. You can use line numbers if you wish,
but they are treated as labels, which means they don't have to be in numeric
order. Labels must be at the beginning of a line and are followed immediately
by a colon ':' (except if the label consists entirely of digits). Not
surprisingly, a label cannot be a Basic command, however Basic can distinguish
a label such as GOTOX from the Basic statement GOTO X, which must contain a
space between the GOTO and the X.

You can indent lines and the indentation will be preserved. If you wish to
indent a line starting with a label, add spaces AFTER the label. All spaces
appearing before a label are automatically removed.

Labels normally start with a letter, and contain letters, digits, or the
underscore character. An exception is line numbers, which don't require a colon
and are treated in all other respects as labels. Upper and lower case are
significant in labels, and labels may not be longer than 31 characters.

Loading and saving Basic programs

Basic programs can be loaded and saved in two formats, Ascii or tokenized.
Tokenized format is compressed and loads faster. However, if I add or change
commands in Storm Basic the token numbers change and a new version will not be
able to load old version tokenized files.

"Save" in the Basic menu or as a Basic command saves in tokenized format. To
save in Ascii format either use the Basic command LIST "Filename" or select
"Save" from the File menu WHEN IN THE BASIC EDITOR ONLY. "Load" as a Basic
command, or from the Basic menu will load either type of Basic file.

Editing your Basic program.

To edit a Basic program just select "Edit" from the Basic menu. A new editing
window will be created with the program currently in memory
displayed there. If there is no program loaded, you will get a blank
editing window to create a new program. The editing window is a full text
editor. You can load, save, and cut and paste to the clipboard. Note: Use
the File menu Load and Save while in the Basic editor, not the Basic menu
Load and Save (they only load and save to the Basic interpreter, not the
Basic editor).

When you have finished editing the Basic program you have two choices.
Clicking on the close box of the Basic editor window will reload the
program into the Basic interpreter. Any syntax errors will be flagged at
this time. Or, you can select "Abort Edit" from the Basic menu and the
editing window will be closed and the program in the Basic interpreter
will not be updated.

The Basic editor will NOT detect errors as you enter code, only when you
close the window and transfer the program back to the Basic interpreter.

While you are editing the Basic program, you can still use the Basic
interpreter to run programs, or even load and run new program. However,
when you close the Basic editing window, any program in the interpreter
will be halted and replaced with the program in the Basic editing window.

Syntax errors:

Syntax errors will indicate a line number. In this context, the program is
numbered internally starting with line 1. So if you get syntax errors and
move to the editing window, refer to the line number in the information
line to see which line of code generated the error.

AUTOEXEC.BAS

When Storm first runs, it looks for a file named AUTOEXEC.BAS in the
current directory (the one that Storm was run from). If found, this Basic
program automatically loads and runs.

=============================================================

Basic Commands

ABORT XFER

Aborts a file transfer, if one is in progress.

APPEND CAPTURE

APPEND CAPTURE "filename" appends the capture buffer to the specified file.

BAUD nn

Sets baud rate to value nn, where nn is a valid baud rate value.
(Range 50 to 19200)


BREAK ON
BREAK OFF
BREAK /

These commands set the hardware break bit in the serial port. To send a
break, use BREAK ON:PAUSE 0:BREAK OFF. Use a longer pause for a longer
break.

To program this into a Storm function key as shift clr/home, add the following
to the STORMKEY.INI file.

[34737]
UseBasic=1
Key="BREAK ON:PAUSE 0:BREAK OFF:END"

If you find the break is not recognized, try a longer pause, e.g.
Key="BREAK ON:PAUSE 1:BREAK OFF:END"


    This function works on all TT, MegaSTE and Falcon serial ports.

CAPTURE ON
CAPTURE OFF
Turn text capture on or off.


CAPTURE /
Toggle text capture from on to off or vice versa.


CARRIER ON
CARRIER OFF
CARRIER CLEAR

Enables or disables carrier detect event trapping, or removes a carrier
event trap entirely. This function works on all TT, MegaSTE and Falcon serial
ports. Event trapping is discussed in full elsewhere.


CD "path"

Sets default path to "path". "path" can be a simple quoted string or
any Basic string expression. This is generally used in conjunction with the
Basic DIR, KILL and other statements which access the file system and would
otherwise require a full filename. Path should end with a backslash '\'.


CHAIN
CHAIN "filename"

Basic allows chaining to a new copy of the Basic interpreter. You can
also specify an optional Basic file to be executed in the new interpeter.
When you execute the CHAIN command, the currently running Basic program is
suspended and the newly created Basic interpeter starts running. You will
see that the Basic window title changes to reflect the level of chaining,
e.g. Basic <2>, Basic <3>, etc.

To exit to the previous Basic, it is only necessary to execute the END
command. The program will continue with the statement following the CHAIN
command.

The level of chaining is only limited by available memory. Each new Basic
interpreter has less than 1K of memory overhead.

It is not possible to share variables between the original Basic
interpreter and a chained Basic. However, you can use the Basic SET
statement in combination with the SET$ and SET functions to save and
retrieve numbers and strings in the STORM.INI and other profile files.


CLIP ON
CLIP OFF
CLIP STOP
CLIP CLEAR

Enables or disabled clipboard event trapping, or removes a clipboard event
trap entirely. Clipboard event trapping is described elsewhere.


CLOSE #n

Closes a file previously opened with the OPEN statement. Attempts to
close a file twice or using an invalid file number will not cause an
error, they will just be ignored.


CLR

Sets all integer variables to zero, undimensions all arrays, and frees all
Basic strings.


CLS

Clears the Basic window.


COM ON
COM OFF
COM STOP
COM CLEAR

Enables or disabled serial port event trapping, or removes a serial port
event trap entirely. Serial port event trapping is described elsewhere.


COMINPUT var$
COMINPUT var$,FULL
COMINPUT var$,HALF

COMINPUT is used to read data from the serial port into a string variable.
All available data (up to a maximum of 256 characters) is read into the
string variable. If no serial data is present, the variable is set to an
empty string.

By default, serial data read using this command is not displayed on the
terminal screen. The optional parameter "HALF" causes serial input to be
echoed to the terminal screen. The optional parameter "FULL" causes both
echo to the terminal screen AND echo back to the sender. Do NOT have half
duplex set when using "FULL" or you may get stuck in an infinite loop!

In order to use this command, you must specify TERM OFF beforehand or else
the regular terminal routines will steal some of the characters.


CONT

Continues execution of a Basic program that has been interrupted either
with the STOP command or the UNDO key or the Basic menu "Break" item.


DATA

Used at the start of a statement to indicate Basic Data items. Data items
can consist of numbers or strings, separated by commas. Strings which
contain leading or trailing blank spaces, commas, or colons should be in
double quote marks. Basic will actually add double quote marks to all
strings in data statements automatically. Data statements can be mixed with
other statements by separating the Data statement from the next statement
with a colon. However, it is more efficient to group data statements
together.


DIM
Allows dimensioning of Basic arrays, e.g. DIM x(2),a$(2) defines two
arrays, one integer and one string. The number inside the bracket is the
maximum array index. Since arrays start at element zero, a value of two
means a total of three elements in the array. Basic allows integer or
string arrays. The maximum number of arrays dimensions is two.

Arrays may not be redimensioned. However, you can use a variable or
expression to dimension an array. e.g. DIM x(a+b-1).


DIR
DIR "string"

Prints out the files in the current directory (set by CD). An optional
string lets you restrict the file listing using wildcards. e.g. DIR
"*.PRG" will list all files ending in ".PRG". To get a directory listing
into Basic string variables, you need to use the FSFIRST$ and FSNEXT$
functions rather than DIR.


DTR ON
DTR OFF

Turns the DTR signal line in the serial port on or off. Useful for forcing
a modem to disconnect.

DTR stands for Data Terminal Ready. Most modems require DTR to be on
before they will operate. It is possible to defeat this feature in most
modems and ignore the state of the DTR line.

This function works on all TT, MegaSTE and Falcon serial ports except for
the TT Serial 1 port, due to lack of documentation.

Example: To force a modem to disconnect, turn DTR off, pause briefly, then
turn DTR back on again.

    DTR OFF
    PAUSE 2
    DTR ON


DUPLEX FULL
DUPLEX HALF
DUPLEX /

Switches duplex to full or half, or toggles duplex between full and half.
Full duplex refers to the ability for each end to send and receive at the
same time. Half duplex means that communication can only occur in one
direction at a time.

However, true half duplex is almost never encountered today and the meaning
of full and half duplex has changed somewhat. Full duplex is applied to
host systems that echo back each character sent to them, while half duplex
is the term applied to host systems that do not echo characters sent to
them, thus requiring the local terminal to echo characters to the screen.
By this definition, GEnie is a half duplex service, even though
subscribers are connected using modern full-duplex modems.


EDIT

This command lets you edit the current Basic program in a separate
full-screen window. You can cut and paste from the clipboard and load and
save the Basic program as an Ascii file or as a tokenised Basic file.


ELSE

Only used in conjunction with the IF statement. If the condition tested in
the IF statement is false, executing passes to the statement following the
ELSE command. IF/ELSE/THEN/ENDIF are discussed later.


END

Terminates executing of a Basic program. Returns to the Ready prompt. If
the program is chained from a previous Basic interpeter, control returns
to the previous program and continues with the statement following the
CHAIN command.


ENDIF

Marks the end of a multi-line IF ... THEN ELSE statement block. ENDIF must
be the first statement on a line (it may be preceded by a label). Each
ENDIF must be matched by the appropriate IF...THEN ELSE statement. Note
that ENDIF is a single word. END IF is not the same as ENDIF.


ENVIRON "aaa=bbb"

Allows you to set environment strings for use by external programs run from
Basic. Environment strings are always consist of a name, followed directly
by an equals sign, then the value associated with that name.

Environment strings are used by command shells, compilers, and various
command line utilities. You will need to refer to the documentation of the
program you want to run from Basic to determine if it uses or needs
environment strings (also referred to as environment variables). However,
the use of the environment on the Atari ST is not nearly as common as it
is on MS-DOS systems.


EXEC mode,"FILENAME","cmdline"

Command used to execute external programs from within Basic. This is
generally used for .TTP type utility programs that may need a command line.
Storm will close and delete its windows, remove its menu bar, clear the
screen, hide the mouse, and display the TOS cursor before running the
program. After running the program, the windows, mouse, and menu bar will
be restored. A few ill-behaved programs may leave the system or mouse in an
unknown state. With TOS 1.4 and later, Storm uses the GEM wind_new call
which should clean up after these programs. For earlier TOS versions, Storm
will try to set the mouse to a known state using published line a
variables, and destroy any replacement desktop. However, Storm will not
attempt to close any open windows, in case they were left open by a desk
accessory.

Note that executing an external program during a file transfer may cause
the file transfer to eventually time out. In general, you should not
execute an external program during a file transfer.

With programs that don't require a command line, just use "" as the command
line argument.

Mode should be 0 for all GEM versions except MultiTOS. With MultiTOS you
can use a mode of 100 to launch a program and then keep Storm running
without waiting for the program to exit. Both programs will multitask when
using mode 100.


FAST ON
FAST OFF

Normally Storm Basic checks for GEM events after each Basic statement. FAST
ON disables this event checking, except when executing a GOTO, GOSUB or any
other command that causes control to switch to another line. This increases
the speed of execution, however you cannot abort the program, switch to
another window, or use any GEM features while FAST is in effect. This is
not quite as restrictive as it sounds. Most programs do contain statements
that switch control to another line. Also, during WAIT, PAUSE, INPUT,
KEYINPUT, DLOAD, ULOAD, and POPUP commands full GEM event handling occurs
because Basic is in a suspended state during those commands.


FKEY nnn,"string"

Assigns a string to a function key or Alt key. The number n specifies
which key is affected.

    For function keys F1 to F10 use the numbers 1 through 10.
    For Shifted function keys F1 to F10, use the numbers 11 through 20.
    The cursor keys numbers are as follows:
    51 is Up        55 is Shift-Up
    52 is Down      56 is Shift-Down
    53 is Right     57 is Shift-Right
    54 is Left      58 is Shift-Left

The reason the cursor keys are fairly high numbers is in case I decide to
add support for control and alt function keys in the future.

To assign a string to a key and have it interpreted as a Basic command,
add 200 to the key number,for both function keys and cursor keys.

If you need to use quotation marks (") inside a function key definition,
CHR$(34) can be used for this purpose.

Example:

FKEY 201,"PRINT "+CHR$(34)+"This is F1"+CHR$(34)

defines (Basic) function key F1 as the Basic command: PRINT "This is F1"

To define ALT-key macros with this command, use the Ascii key value as the
key number.

Example:    FKEY ASC("A"),"BAUD 1200"

Rather than look up the Ascii key value of "A" in a table, let Basic do
the calculation for you with the ASC function which returns the Ascii
value of a letter.

It is also possible to define an ALT-key macro which is NOT a Basic
command, something which you can't do with the Alt-Key dialog. Just use
the Ascii value of the lower case key.

Example:    FKEY ASC("a"),"This is Alt A"


FOR

Statement starting a FOR ... NEXT loop. There is one peculiarity of FOR
NEXT statements in Storm Basic. The loop will always execute at least
once, no matter what the start and end values are set to.


GEM mode,"FILENAME","cmdline"

GEM is similar in effect to EXEC, except that it leaves the mouse on and
doesn't turn the TOS cursor on. A command line is still required. A few
GEM programs will accept a command line.

Most GEM programs require the current path and drive to be set to their home
directory in order to load their resource files. You should use the Basic CD
command to set the appropriate path before using GEM OR pass a fully specified
filename, which will cause Storm to set the current path and drive to that
path. Storm will save and restore the previous path and drive when executing
this command.

    Notes on GEM and EXEC with MultiTOS.

The behaviour of GEM and EXEC with MultiTOS is different from regular TOS.
Windows are NOT closed because it is possible to launch another program
and then continue to run Storm.

GOSUB label

Jumps to a subroutine at the indicated label. The label must exist or an
error will occur at run time. Line numbers are not required in Storm
Basic, though Storm Basic will accept line numbers. Return from a
subroutine is by means of the RETURN statement. If you do wish to exit
from a GOSUB without using the RETURN statement, you should use the POP
statement to remove the return address from the Basic stack.

GOTO label

GOTO transfers control unconditionally to a line with the indicated label.
If the label doesn't exist, an error will occur at run time.

HELP topic

Searches the HELP.INI file for information on a topic and prints any help
information in the Basic window. There is no need to use quote marks
around the topic name. You cannot have any other Basic commands on the
same line as the Help command. HELP HELP lists the available help topics.

HELP.INI is the help file. It is like the other profile files in that each
help topic is enclosed in square brackets. However, the text between each
topic is plain Ascii text. The only restriction is that help text should
not start with a square bracket so it won't be mistaken for a new topic.
Help topics MUST be all uppercase in the HELP.INI file.

You can edit the HELP.INI file in Storm and customize it as you wish. If
you don't want online help, just delete or rename HELP.INI.


IF

Starts a conditional statement. There are two forms of the IF statement in
Storm Basic. The first form is the single line form. Example:

    IF X > 10 THEN PRINT "X > 10" ELSE PRINT "X <= 10"

The IF statement requires a THEN statement at all times. The THEN statement can
be followed by any Basic statement, or by a line label. You can also use the
ELSE statement after the IF THEN block to indicate what action to take if the
condition tested by the IF statement is false. The ELSE statement can also be
followed by a line label.

Note that if a line label follows a THEN or ELSE statement, no GOTO is
required. Also, any statement following the line label will be ignored because
control has already been transferred to the new line.
e.g.

    IF X > 10 then Label:print "This never gets executed"

The second form is the multiline IF THEN ELSEIF statement:

IF expr THEN
{statements}
...
ELSE
{statements}
...
ENDIF

In the multiline IF/THEN statement, the IF must be the first statement in
the line and the THEN must be the last statement, to be recognized as
starting a multi-line IF/THEN sequence. (However, a label and/or spaces
may appear before the IF.)

The ELSE and ENDIF also must appear at the start of a line. (May be
preceded by a label and/or spaces.)

IF/ELSE/ENDIF may be nested. An ELSE or ENDIF without a matching IF will
be flagged as a syntax error.

Note:The 'ELSE IF' statement is NOT supported in Storm Basic.


INPUT variable
INPUT "prompt";variable

Prompts the user for input in the Basic window. The standard prompt is a
question mark. You can add an optional quoted string which will appear in
front of the question mark. While Storm is waiting for input, all other
program functions can be accessed. You can even switch away from the Basic
window to another window. Event trapping is disabled during INPUT
processing.

'Variable' can be any Basic variable, including an array reference.

INPUT #n,variable

This form of the INPUT command is for reading data from a file into a
Basic variable. 'n' represents a valid file number The file must
previously been opened with the Basic OPEN command. Using an invalid file
number causes an error.


KEYINPUT X$

Waits for you to press a key in the terminal window and then returns that
key in the string variable. Works only in the terminal window. However, if
you are using typeahead, it will return characters from the typeahead at
the point that they are transmitted out the serial port.

If keyboard macros are active, KEYINPUT reports the characters in the
macro one by one, rather than reporting the keystroke that generated the
macro. There is no action if the keystroke doesn't generate any serial port
output, e.g. unassigned function keys.

For proper operation, use TERM OFF before the KEYINPUT command to prevent
missing any characters.


KILL "filename"

Deletes the specified file(s) from the disk. Wildcards are allowed. Use
caution with this command, especially with wildcards.


LET

A seldom used keyword. Can be used in front of assigment expressions.
e.g. LET x = 1


LFEED ON
LFEED OFF
LFEED /

LFEED ON causes a line feed to be generated internally every time a
Carriage Return character is received. LFEED OFF turns this feature off.
LFEED / toggles the line feed setting between on and off.


LINE INPUT var$
LINE INPUT "prompt";var$

Reads an entire line of input from the Basic window into a string
variable. You can optionally select a prompt to be displayed.


LINE INPUT #n,var$

Reads an entire line of input from a file into a string variable. The line
ends when a line feed is encountered, or 255 characters have been read,
whichever comes first. You should open an Ascii file in text mode (see
OPEN) for proper results using this statement.


LIST
LIST "filename"
LIST label1,label2
LIST label
LIST by itself lists the current program in the Basic window.

LIST "filename" saves the current program to the file "filename" as an
Ascii file.

LIST label1,label2 lists all Basic lines between the two labels.

List Label lists the Basic line that begins with 'label:'.


LOAD "filename"

This loads the file "filename" into Basic. The file can either be an Ascii
file or a tokenized Basic file. Storm will figure out what type of file it
is automatically. Loading a file erases any other program in memory.


LOAD CAPTURE "filename"

Loads the specified file into the capture buffer.

LOAD TERM "file.emu"

Load a terminal emulation module into Storm. Note that this just loads the
terminal emulation; you need to use the MODE command if you want it to be
the active emulation. There is no check to see if the emulation is already
loaded. The maximum number of loaded terminal emulation modules is six,
which doesn't include the built-in TTY terminal emulation.

The STORM.INI profile file section [Terminal] contains a list of currently
loaded terminal emulations. e.g.:

[Terminal]
Term1=C:\STORM\VT100.EMU
Term0=C:\STORM\VIDTEX.EMU

There is a memory-resident profile file names ENV which contains further
information about loaded terminal emulation modules. The terminal
emulations are listed by emulation names:

[Terminal]
Term1=VT100
Term0=VIDTEX


The following code lists currently loaded terminal emulations. Note that
the built-in terminal emulation TTY is always present.

FOR i = 0 to 5
x$ = "Term" + STR$(i)
PRINT i;"";SET$("STORM","Terminal",x$)
PRINT i;" ";SET$("ENV","Terminal",x$)
NEXT i
' Current emulation is listed by name under "Current"
PRINT "Current=";SET$("STORM","Terminal","Current")

LOAD XFER "file.trf"

Loads a file transfer module into Storm. There is no check to see if the
same module has already been loaded. The maximum number of loaded file
transfer modules is six. (This doesn't include the Ascii file transfer,
which is built-in). If you want to check to see what file transfer modules
are present, there are several methods.

First of all, the STORM.INI profile file section [Protocols] lists the
currently loaded file transfer modules by filename. e.g.:

[Protocols]
Xfer2=C:\STORM\ZMODEM.TRF
Xfer1=C:\STORM\XYMODEM.TRF
Xfer0=C:\STORM\BPLUS.TRF

Secondly, there is a memory-resident profile file named ENV which also
contains information about loaded protocols. It contains two types of
entries under the [Protocols] secton.

The first type of entry, "Xfer0=name" lists the internal protocol name.
The second type, "Popup0=name" lists the individual protocol names. e.g.:

[Protocols]
Xfer0=Bplus
Xfer1=XYMODEM
Xfer2=ZMODEM
Popup0=Ascii
Popup1=Xmodem
Popup2=Xmodem-1K
...
Popup6=Zm. Resume

Note that the first popup name is always Ascii, which is an internal
protocol. There are more protocol names than modules, since a module can
contain several protocols.

The following code example will list information about all loaded file
transfer protocols.

FOR i = 0 to 5
x$ = "Xfer" + STR$(i)
PRINT i;"";SET$("STORM","Protocols",x$)
PRINT i;" ";SET$("ENV","Protocols",x$)
NEXT i
'
FOR i = 0 to 11
x$ = "Popup" + STR$(i)
print i;" ";SET$("ENV","Protocols",x$)
NEXT i


LOG

Acts like Basic PRINT statement, but output is goes to the capture buffer.
Still has a few quirks, for example it doesn't actually update the capture
buffer display until a newline is printed. Also, the cursor is not repositioned
in the capture buffer.

LPRINT

Prints to printer port using typical Basic syntax.

MENU n1,n2

Allows a Basic program to simulate selecting a Storm menu item. n1 is the
menu title index, where Desk=0, File=1, Edit=2, etc. An out of range menu
title number will cause a Basic error.

n2 is the item number in the menu dropdown, with the top item being number
1. Do not count separator lines as items. e.g. "Exit" is item number 10 in
menu number 1. An out of range item number will be ignored. Disabled menu
items will not be executed, since they were probably disabled for a good
reason! This command is useful for programming ALT key macros.

It is not possible to select desk accessories using the MENU statement.


MERGE "filename"

Loads the file "filename" and appends it to the end of the program in
memory. "filename" must be an Ascii format file, not a tokenized file.


MID$(dest$,start[,length]) = new$

Replaces a portion of destination string with a new string.

dest$ is a string variable or a string array reference.
new$ is a string which will be used to replace a portion of dest$.
Length is an optional number specifying the number of characters to replace.
Start is a number specifying the position where you want to start replacing.

If length is not specified, then the length of the new$ string will be
used, as long as it is not longer than the dest$ string.

Note: The length of the destination string is never changed by this
command; the replacement text just overwrites the specified portion of the
destination string. If the new$ is shorter than length, then the length of
new$ is used for replacement.


MKDIR "dirname"

Creates a folder (directory) using the specified name. An error will occur
if dirname already exists or an invalid path is specified.


MODE "name"

Sets terminal emulations to "name", where "name" is the name of a loaded
terminal emulation. No error is caused if the emulation is not found. If
the terminal emulation is already the active emulation, it will be
re-initialized.


NEW

Erases the program in memory, including all variables and arrays.


NEXT

Used in conjunction with the FOR statement. You can specify a loop
variable, e.g. NEXT x, or leave it blank in which case NEXT will loop to
the most recent FOR statement. You cannot use a list of variables, as in
some Basics. e.g. NEXT x,y,z is not legal in Storm Basic.


ON

ON is used for a variety of purposes. The standard usage is to change the
flow of control according to the result of an expression.


ON expr GOSUB label1,label2,label3,...
ON expr GOTO label1,label2,label3,...

In these two cases, expr is any valid Basic expression, e.g. x+1, x/y or
the name of a Basic variable. expr is evaluated and the result is used to
determine which label to branch to. If the result is one, the first label
in the list is used, if the result is two, the second label, and so forth.
If the value is less than one or greater than the number of labels in the
list, then control passes to the next statement.


ON event(n) GOSUB label

Event trapping

Event trapping is a way of responding to events without having to constantly
watch for them. When trapping is enabled on an event, Storm will check for the
event between executing each statment and, if the event occurred, jump to a
user-defined subroutine to handle the event. Multiple event traps are possible,
though Storm blocks the current event from being trapped again while its trap
routine is executing.

Currently there are four events you can trap for; timer, carrier detect,
serial port and clipboard.

Event trapping can occur during executing of PAUSE, WAIT and KEYINPUT
statements. It cannot occur during INPUT or LINE INPUT while Basic is
waiting for a line of input in the Basic window or GEM functions such as
POPUP, LISTBOX and FSEL$.


ON TIMER(n) GOSUB Label
TIMER ON
TIMER OFF
TIMER STOP
TIMER CLEAR

The statement ON TIMER(10) GOSUB Label tells the computer that every ten seconds
it should branch to the subroutine at line Label. The timer value is checked
between execution of each statement, and also checked during WAIT, PAUSE and
KEYINPUT commands.

The ON TIMER(n) gosub statement is actually a way of telling the computer
to set up a timer event. To enable the event, you must also use TIMER ON.
TIMER OFF disables event trapping.

TIMER STOP is actually used by Basic internally to block the timer event during
event processing. It stops event processing, but doesn't reset the
timer count. Use TIMER OFF to disable the timer event.

Warning: Do not reenable an event during the event subroutine. It can lead
to unexpected results and may crash the program.

TIMER CLEAR is used to erase the timer event trapping completely.


ON CARRIER(n) GOSUB Label
CARRIER ON
CARRIER OFF
CARRIER STOP
CARRIER CLEAR

Similarly, you can perform event trapping on the carrier detect signal.

ON CARRIER(1)... waits for carrier detect to become TRUE, while ON CARRIER(0)..
waits for loss of carrier. However, when you return from a carrier event trap,
the trap sense is automatically reversed.


ON CLIP(n) GOSUB Label
CLIP ON
CLIP OFF
CLIP STOP
CLIP CLEAR

Clipboard event trapping lets you call a subroutine each time the user
copies or cuts text to the clipboard from a STORM window.

ON CLIP(n) selects clipboard trapping. The numeric parameter selects what
type of clipboard selection to trap. CLIP(1) only traps copying from the
terminal screen. CLIP(2) traps copying from the capture buffer window.
CLIP(4) traps copying from any editing window, including the typeahead
buffer and the capture buffer.

As noted above, it is possible to have all events enabled simultaneously.
You can also use WAIT or PAUSE or KEYINPUT during an event handling subroutine.
As an example, you could have a PAUSE while executing a timer event
subroutine. If a carrier event occurred during the pause, the carrier event
subroutine would be executed, then the PAUSE would continue, then eventually
the main program would continue.

It is possible to short-circuit an event subroutine and jump to another
line in the program. You should clear the event, use the POP statement to
clean up the Basic stack, then GOTO to continue. If you want to continue
the event trapping after this, you should re-enable the event completely
by executing an ON event(n) GOSUB statement.

One reason you might do this is if you had a carrier event enabled to
detect loss of carrier during an online session. If carrier is dropped,
you would not want to continue executing statments which wait for the other
end to respond.

If you forget the RETURN at the end of the event subroutine, execution will
continue with the next line. If the event subroutine is at the end of the
program, the program will end with no warning.

More on event trapping.

When an event trap jumps to a subroutine, it first saves the state of any
WAIT, PAUSE, or KEYINPUT in progress. While in the event subroutine, no
checking will be done for the pending WAIT, PAUSE, etc. However, you are
free to use WAIT, PAUSE, or KEYINPUT during an event subroutine. When the
event subroutine returns, the original WAIT, PAUSE, or KEYINPUT will be
restored and can continue.

If you set TERM OFF in your main program, then TERM will be off in the
event subroutine unless you explicitly turn it on with TERM ON, or implicitly
turn it on with a WAIT or PAUSE or KEYINPUT.


ON COM(0) GOSUB Label
COM ON
COM OFF
COM STOP
COM CLEAR

Use ON COM(0) to set up an event trap for the serial port. Whenever characters
are available at the serial port, the specified subroutine is
executed. You should use COMINPUT in the event subroutine to empty the
serial port otherwise the event subroutine will be executed repeatedly.

    COM ON enables the event trap.
    COM OFF disables the event trap.
    COM CLEAR removes the event trap.


OPEN "mode",#n,"filename"

Opens a file in Basic. n is a digit from 1 to 15 which is the file number
that is used in subsequent input # or print # commands.

"mode" actually uses C language syntax. "mode" can be one of the following:
    "w" creates a text file for writing, discards previous contents.
    "r" opens a text file for reading.
    "a" append; opens or creates a text file for writing at end of file.
    "r+" opens text file for update (reading or writing).
    "w+" creates text file for update, discards previous contents.

Adding a "b" to mode, e.g. "wb" opens the file in binary mode. Text mode is
supposed to do CR->CR/LF translation so that a CR-LF combination in the file
is replaced with a single line feed character when you read from the file,
e.g. with LINE INPUT #n. When writing to a file in text mode, a carriage
return is written as a carriage return followed by a line feed.


PARITY ODD
PARITY EVEN
PARITY NONE

Sets parity for the serial port, odd, even, or no parity. Word size is
automatically set to 8 bits for no parity, 7 bits for even or odd parity.


PAUSE nn

Pauses execution for nn seconds. While the pause is in effect you are able
to switch away from the Basic window. Terminal operation continues during
the pause. Specifying -1 for the pause value generates the absolute
maximum pause, which is over ten million seconds (about 124 days). Event
trapping is enabled during PAUSE. The terminal window continues to receive
and display characters if TERM is set to ON.


PLAY string$

Uses the GEM Xbios function Dosound call. The sound values must have been
read into a string variable or string array variable. A number of programs
available through online services are able to generate appropriate data
values for the Dosound function. Unfortunately, if the keyclick sound is
enabled, pressing any key will abort Dosound. The same is true if the
system bell sound is enabled and it is sounded. You should not alter the
string variable contents while the sound is playing or unexpected results
may occur.


POP

Pops a return value from the Basic runtime stack. Each time you call GOSUB
or start a WHILE loop six bytes of return information are put on the Basic
runtime stack. Exiting from a subroutine or WHILE loop by means of GOTO
leaves this information on the stack. The stack will keep growing in this
situation until you run out of memory. Use of POP is recommended to keep
the stack small. You can also use POP if you exit from within a FOR/NEXT
loop using a GOTO. This also leaves information on the stack. However, when
you start a new FOR/NEXT loop with the same loop variable, any old
reference to the same variable is removed from the stack automatically.


PRINT

Basic Print statement. Uses typical Basic syntax. However, PRINT USING is
not supported. Neither is TAB(n) supported. Semicolons or commas are
ALWAYS required between items to be printed.


PRINT #n

PRINT #n prints to a file where n is a file number of a file previously
opened with the OPEN command. However, PRINT #0 will print directly to the
terminal screen. PRINT #0 sends text to the terminal screen using the
current terminal emulation, so that you can use escape sequences and other
terminal emulation features. Text displayed in this manner is not sent out
the serial port, nor is it detected by the WAIT or KEYINPUT commands. No
linefeeds are added unless you use LFEEDS ON.


READ var,var$,var(n),var$(n)

Reads an item from a DATA statement into a Basic variable. You can read
into any variable or array variable. Attempting to read a string value
into an integer variable will cause an error. However, you can always read
an integer value into a string variable; it just gets converted into the
ascii representation of the value.


REM

Indicates a Basic comment. You can also use ' to start a comment.


REPLACE$(dest$,start[,length]) = new$

Replace$ is a lot like MID$, except that it will expand or shrink the
destination string. This means you can replace a part of string with a
string that is a different length. Used REPLACE$ in place of awkward
left$+"xxx"+right$ constructions to alter strings.

Example: Generic replacement of "Street" with "St."
    a$ = "336 Queen Street South"
    ...
' Assume we don't know where "Street" starts or what case it's in.
' Use UCASE$ to create a copy of a$ that is uppercased.
' Search for "STREET" and replace in original a$ with "St."
    x = instr(UCASE$(a$),"STREET")
    if x then replace$(a$,x,6) = "St."
    print a$

This changes a$ to "336 Queen St. South". If you don't specify the
replacement length, then it defaults to the length of that portion of the
destination string from 'start' to the end of the string. e.g. in the
above example, REPLACE$(a$,x) = "St." would change a$ to "336 Queen St.".

Something like REPLACE$(a$,x,y) = "" is also permitted. It deletes the
specified portion of the destination string.


RESTORE
RESTORE label

RESTORE by itself resets the data pointer for subsequent READ operations
to the start of the Basic program. You can use an optional label to
restore the data pointer to a specific line.


RETURN

Returns from a GOSUB call.


RMDIR "dirname"

Deletes a subdirectory (folder). You cannot delete a subdirectory that
contains files. You must delete all the files first.


RUBOUT ON
RUBOUT OFF
RUBOUT /

Sets the terminal Destructive Backspace setting. RUBOUT ON means that
backspace characters (Ascii 8) received by the terminal cause the previous
character on a line to be erased, unless the cursor is already in column
zero, in which case nothing happens.

RUBOUT / toggles the state of Destructive Backspace.

RUN
RUN "filename"

RUN by itself just runs the program in memory. RUN "filename" loads a new
program and then runs it. The program can be a tokenized Basic program or
an Ascii Basic program.

RUN always zeros variables and strings before the program starts.


SAVE "filename"

Saves the program in memory as a tokenized Basic file. This is a more
compact format than Ascii, though it can only be read and understood by
Storm Basic. Tokenized files also load faster than Ascii files.


SAVE CAPTURE "filename"

Saves the capture buffer to the indicated filename. If you want to be
prompted with a file selector, use SAVE CAPTURE FSEL$("","").


SBITS 1
SBITS 2
SBITS 3

Sets the number of stop bits used by the serial port. SBITS 3 actually
sets stop bits to one and a half (1.5) stop bits.


SEND

Acts the same as PRINT, except output is to the serial port instead of the
Basic window. As with PRINT, SEND will automatically add a carriage return
unless you end the statement with a semicolon or comma. You can send any
control characters using SEND, including Ascii 0, by using CHR$(n). If
half-duplex is set, characters will be echoed to the terminal screen.

SET
Used to set profile file settings. The current profile files are:

STORM.INI        Used for all Storm terminal settings.
STORMKEY.INI    Used to set keyboard macros.
DIALDIR.INI        The dial directory.

The profile files are Ascii text files separated into sections. Each
section is labelled with a name inside square brackets, followed by a
number of entries of the type Setting=Value.

Value can be an integer value or a string, or a quoted string. Profile
files are loaded into memory when Storm runs and are saved when you exit,
or can be saved manually from the menu bar. Some items in the profile file
are only accessed when you first run Storm, others are accessed
constantly.

e.g. Keyboard macros are always retrieved from the STORMKEY.INI file in
memory. Serial port settings are only retrieved from the profile file
initially, though the profile settings are kept up to date each time the
serial port settings are modified. Full documentation on the profile files
will come at a later date.

Example: to set the download path use:

SET "STORM","Paths","DownloadPath","F:\DOWNLOAD\"

The first string is the profile file name, minus the extension. The second
string is the section name, the third string is the name of the item to be
modified. The fourth string is the new value of the item. The fourth item
can be a string or a integer. If the string contains control codes or begins
with a quote character ("), it is automatically quoted and control codes
converted into standard C language escape sequences.

e.g. Ascii 10 becomes \n, Ascii 27 becomes \33, Ascii 127 becomes \177

You can create your own sections in the profile files for your own
purposes and they will be created if they don't already exist.

Currently only the predefined Storm profile files "STORM.INI",
"STORMKEY.INI","DIALDIR.INI", and "HELP.INI" are fully supported.

You can specify another profile file name and access entries in it, but it
will exist only in memory. It will not be loaded (even if it exists) and it
will not be saved to disk.

Profile sections items are case-sensitive. You must type the names exactly as
they appear in the profile file.


STOP

Stops the program. You can restart the program with CONT. Variables remain
unaffected.


STRIP ON
STRIP OFF
STRIP /

Sets whether the high bit is masked off when reading from the serial port.
Useful when connecting to a system transmitting parity when you have
parity off. STRIP / toggles the current setting.


TA ON
TA OFF
TA /

Turns typeahead on or off, or toggles the state of typeahead. When
typeahead is turned on, a cursor is displayed in the typeahead window and
you can enter text there.


TERM ON
TERM OFF

Normally, when Storm and Basic are running, the terminal window and Basic
program execution proceed in parallel. This means that under some
circumstances, you can miss a string you are waiting for because Basic is
executing another line of code while the terminal is processing serial
input. So when a WAIT statement comes up again, the string has already
been processed by the terminal.

This is only a problem when the strings are separated by very short
pauses. In order to cure this, you can use the TERM statement to shut off
terminal processing except during WAIT statements. This will guarantee that
every single character that comes in the serial port will get checked by
the WAIT statement. If that's what you want, use TERM OFF where you want
strict serial port checking to start, and TERM ON where you don't really
care.

TERM is ON by default and is automatically turned back on when a Basic
program is stopped or ends. It is also turned on during WAIT, PAUSE, and
KEYINPUT commands.

For example, if you want to catch prompts between each message at 9600
baud, use TERM OFF. If you only want to catch the prompt at the end of a
process that will take a while, leave term on.


TIMER ON
TIMER OFF
TIMER STOP
TIMER CLEAR

See description of timer events under event trapping.

TOPW
TOPW n

TOPW by itself brings the Basic window to the top. TOPW followed by a
number brings the specified window to the top. The window number is based
on the Windows menu dropdown.

    1 is the Terminal window
    2 is the Capture window
    3 is the Basic window
    4 through 10 are editing windows (only topped if actually open)
    11 is the file transfer window (only topped if open)


TRAP label

Generates an error trap so that when a Basic error occurs, Basic will do a
gosub to the label in the trap statement. Currently return from the trap
routine should be by a RETURN statement to continue execution by
re-executing the statment that generated the error. Or, you can do a POP
statement to pop the return off the stack and then GOTO any other line.

ERR(0) returns the Basic error number (listed elsewhere). ERR(1) returns
the line number in which the error happened. Line numbers for this purpose
start at one for the first line in the file.

After the trap routine is entered, you need to reset the trap handler with
another TRAP statement before proceeding.


TRON
TROFF

Turn tracing on or off. This can be done inside a program, from the Ready
prompt, or the Basic menu dropdown. When tracing is enabled, line numbers
inside square brackets are printed as each line is executed.

As with the TRAP statement, Basic programs are numbered sequentially,
starting at line one.


TYPE



UNLOAD XFER "name"
UNLOAD TERM "name"

Unloads a file transfer (XFER) or terminal emulation (TERM) from memory.
Use the name that appears in the Terminal Emulations or Transfer Protocols
dialog box. e.g "VT100" or "ZMODEM". See "LOAD XFER" and "LOAD TERM" for
code showing how to find the names of currently loaded file transfers and
terminal emulations.

Note that unloading a terminal emulation sets emulation to the default TTY
emulation. Be sure to reset terminal emulation with the MODE command
afterwards. If the module is not found, no error occurs.


WAIT nn,"string"[,"string",...]

This is the most important command for automated operation. You can wait
for multiple strings with a timeout value (in seconds). Basic will match
characters coming in the serial port with the strings and continue with the
next statement when either the string is matched, or a timeout occurs.
Naturally, all program functions are enabled while the wait is in
progress.

A timeout value of -1 waits forever (actually, about 124 days).

Once the WAIT statment has executed, use the WAIT(0) function to determine
the result.

WAIT(0) returns 0 if there was a timeout, otherwise it returns the string
number that was matched, starting at 1 for the first string. So you could
use ON WAIT (0) GOSUB 100,200,300,etc.


WHILE expr
    statements
WEND

While the expression evaluates to TRUE, executes the statements inside the
loop. If the expression is FALSE, skips to the next statement past the
WEND statement. A WHILE/WEND block can span multiple lines and can begin or
end in the middle of a line.


===========================================================

Basic functions and operators

Functions in Storm Basic generally take a set of arguments and return
a value. Functions whose name ends in a dollar sign ($) returns a
string value. All other functions return a numeric value. All numbers
in Storm Basic are 32-bit signed values.

Certain keywords like CLIP$, CARRIER, and CSRLIN return a value but,
unlike true functions, have no arguments.

ABS(n)

Basic function returns the absolute value of a single numeric argument.


ALERT(1,"[1][alert][OK]")

Lets you display a standard GEM alert box. The number is the number of the
default button. The string must be a proper GEM alert string. No checking
is done of the string. The return value is the number of the button that
was selected.


AND

Performs a bitwise Boolean AND operation between two numeric values.


ASC("x")

Function which returns the Ascii value of the first letter of a string
parameter.


CAP$(n)

String function which returns a line of text from the capture buffer. The
numeric parameter indicates which line to return. The first line of the
capture buffer is line number one. An out of range number will return an
empty string. A blank line will also return an empty string. The line of
text is not terminated by a carriage return or line feed.


CAPTURE

Returns TRUE if Capture is enabled, otherwise FALSE. No parameters are
required. e.g. PRINT CAPTURE will print -1 if Capture is enabled or 0 if it
is not.


CARRIER

Returns TRUE if the carrier detect signal on the serial port is on,
otherwise returns FALSE. No parameters are required. This function works
on all TT, MegaSTE and Falcon serial ports

CHR$(n)

Returns a string consisting of a single character with the Ascii value of
the numeric parameter.


CAPTURE CLEAR

Clears the capture buffer.


CLIP$

CLIP$ returns the contents of the clipboard. If the clipboard is empty,
CLIP$ returns the empty string "". The maximum size of CLIP$ is 65535
bytes.

CLIP$ can consist of multiple lines, separated by a line feed character.
Even if you select a single letter, the program will still add a line feed
to it, so always be prepared to strip out the line feed character, e.g.
with RTRIM$.


CSRLIN

Returns the terminal screen cursor row location. No parameters required.
The top line of the terminal screen is line 1.


DATE$

DATE$ returns the date as a string in the format mm-dd-yyyy


DFREE("A")

Returns free space on a drive. The parameter is a string consisting of
drive letter you want information on.


DLOAD("protocol","file",...)

Example:  x = DLOAD("XMODEM","FILE")

This downloads the file "FILE" using the Xmodem protocol. The 'x' will
contain the number of files actually transferred, in this case '1' if
successful, '0' if there was an error. If you omit the filename, the
protocol module will automatially put up a file selector if required by
that protocol. If you abort the transfer, the return value will be 0. If
you abort the Basic program, the file transfer will continue.

Protocol names should be the same names as listed when downloading via the
File menu. Upper and lower case are not significant. Basic will search
through the list of available protocols. If the protocol is not found, a
Basic error will result.

You can use multiple filenames, but non-batch protocols, e.g. xmodem, will
only transfer the first file. Wildcards are NOT permitted in the
filenames. However, you could expand wildcards using the Basic functions
FSFIRST$ and FSNEXT$.


DRVMAP$

Returns a string with letters indicating which drives are available on the
system. e.g. "ABCDE" indicates drives A through E. The letters are always
uppercase. Note that 'A' and 'B' can both be present, even if the system
has only a single floppy drive because GEM can simulate drive B
internally.


ENVIRON$("name")

Returns the value of an environment variable. The parameter is the name of
the environment variable (environment string) you want information about.
A nonexistent variable returns an empty string.


EOF(n)

Returns TRUE of the end of a file has been reached. Used when reading a
file to detect the end of the file. 'n' is the file number.


ERR(0)

Returns the Basic error number of the most recent Basic error.

Current error numbers and error messages:

0   "Unknown Error" (or no error at all)
1   "Expression too complex"
2   "Invalid NEXT"
3   "NEXT without FOR"
4   "Invalid RETURN"
5   "Out of data on READ"
6   "Illegal parameters"    (fairly generic error)
7   "No more variables (max 128)"
8   "Out of memory"
9   "Undefined line number"
10  "Subscript out of range"
11  "Attempt to redimension"
12  "Out of string space"
13  "Bad load file format"
14  "File I/O error"
15  "Can't open file"
16  "Can't write file"
17  "Can't read file"
18  "Stack Underflow"
19  "Divide by zero"
20  "ELSE without IF"
21  "WHILE without WEND"
22  "WEND without WHILE"
23  "Syntax errors during load"
24  "Error token encountered"
25  "String too large"
26  "Badly formed label"
27  "Duplicate Label"
28  "Wrong Data Type"
29  "ENDIF must be at start of line"
30  "IF must be at start of line"
31  "ENDIF without block if"
32  "ELSE without block if"


ERR(1)

Returns the line number where the last error occurred. Basic programs are
numbered internally starting at line 1.


FRE(n)

Because Basic allocates and deallocates memory as needed, most FRE calls
return how much memory is used, not how much is free. Most of these values
are only useful for debugging purposes.

FRE(3) returns the number of characters waiting in the serial buffer. It
is somewhat useful when figuring out if you are at a prompt, but not 100%
effective with time-sharing systems, where long pauses are not uncommon.

FRE(2) returns the number of bytes in the capture buffer. It does this by
counting the number of characters in each line. It does not take account
of any overhead used to keep track of the capture buffer.

FRE(1) returns the number of lines in the capture buffer. It will always be
at least 1, because there is always at least a single blank line.

FRE(0) returns the largest available free memory block in the system, that
is, the result of calling Malloc(-1L)

FRE(-1) returns total space used for strings (not including system
overhead).

FRE(-2) returns the total number of string slots currently allocated. This
is never less than 16.

FRE(-3) returns the number of strings currently in use.

FRE(-4) returns the number of bytes used for storing the current program
statements.

FRE(-5) returns the size in bytes of the variable name table. Each
variable name is stored as a null-terminated string. There are two extra
null bytes to mark the end of the table.

FRE(-6) returns the size in bytes of the variable value table. Each
variable takes 8 bytes of storage.

FRE(-7) returns the size in bytes of the array table. Each element of an
array takes 4 bytes in this table.

FRE(-8) returns the size of the run-time stack. This is typically 64
bytes, unless you have very deeply nested loops.

FRE(-9) returns the number of labels in the label table.

FRE(-10) returns the size in bytes of the label name table.

FRE(-11) returns the number of bytes allocated to the capture buffer. This
is usually more than the number of bytes actually used. Mostly of academic
interest.

Any other value inside the brackets returns the same as FRE(0).


FSEL$("path","filename")

Pops up the GEM file selector and returns a filename. "path" lets you specify
the path to be displayed by the file selector. An empty path ("") will cause
the default path to be used. A path starting with a backslash will be in the
root of the default path's drive. A path with a colon character (:) as the
second character is used as-is. Any other path is appended to the current path.

You should either end the path with the wildcard you want to use, or end it
with a backslash, in which case the default wildcard "*.*" will be added.
Or, use just a wildcard to have it added to the default path. e.g.
FSEL$("*.BAS","");

"filename" is the filename to be displayed in the file selector. A blank
filename is permitted. e.g. FSEL$("","") just pops up a file selector with
current path and default wildcard "*.*" and an initially empty filename.

If you select Cancel then FSEL$ returns an empty string. If you select OK,
but the filename is blank, then an empty string is returned.


FSELPATH$("path")

Pops up the GEM file selector and returns the path only. If you select
Cancel, it returns an empty string. "path" lets you specify a starting
path. "path" should be a full path including drive letter and should end
with a backslash, An empty path ("")  will cause the default path to be
used.

FSFIRST$("filespec",mask)
FSNEXT$

These calls are used to get a directory into string variables.

FSFIRST$ corresponds to the GEMDOS Fsfirst call. The filespec is a wildcard
value, which can include a full directory path. mask is an integer value
representing which files you wish to view. The mask values are:

1   File is read-only
2   File hidden from directory search
4   File set to "system"
8   Volume label
16  Directory
32  "Archive bit" meaning file has been updated.

Add the mask values together to generate an appropriate mask. You are best
of always specifing the "Archive bit" because you never know what state it
is going to be in. The DIR command uses a mask of  49, which is equal to
32+16+1.

Note that FSFIRST$ and FSNEXT$ will return the two directory entries of '.'
and '..' which are found in every directory and are used by TOS
internally.

Once you call FSFIRST$, then keep calling FSNEXT$ until it returns an empty
string.
Example: This prints out the current directory.

PRINT FSFIRST$("*.*",31)
X = 1
WHILE X
    a$ = FSNEXT$
    IF a$ = "" THEN X = 0 ELSE PRINT a$
WEND

Sample output:

----d-          0 1991/06/06 11:00:00 AUTO
-----a        123 1992/08/25 12:12:11 DESKTOP.INF


The first six characters are file attributes. The possible attributes (in
order of appearance) are:

r    =    Read Only
h    =    Hidden File
s    =    System File
v    =    Volume Label
d    =    Directory
a    =    Archive Bit

    Any attribute not present is replaced with a '-'.

The attributes are followed by a single space, then a ten character field
for the file size, then the date, time and filename as shown above. The
fixed size fields make it easy to extract desired information using the
MID$ function.


INSTR([start,]"string","key")

This is a string search function. It searches "string" for substring "key"
and returns the location of "key" in "string", or 0 for failure.
'start' is optional and is the location in the string to start at. N.B. The
first location in a string is location 1. Also, no matter where you start
searching in the string, INSTR always returns an index relative to the
start of the string.

    Example: INSTR("12345","3") and INSTR(3,"12345","3") both return 3.

ISDIGIT("string")

Returns TRUE if the first character of the string argument is a digit.
Returns FALSE if it is not a digit.


LCASE$("string")
    Returns a copy of a string converted to all lowercase characters.


LEFT$("string",n)
    Returns a string containing the leftmost n letters of the string.


LEN("string")
    Returns the length of a string.


LISTBOX(title$,array$(n),count)

This is a new GEM based method of asking for user input. The listbox
displays a list of text items in a box with slider, scroll bar, arrows,
and a title. The number of items that can be used in a listbox is limited
only by Basic memory limits. The listbox call returns the index of the
item selected (starting with 1) or zero if no item was selected.

title$ is a string or string expression which is used as the title for the
listbox. array$(n) is the starting array location for the start of the
listbox data. Count is the number of items from the array to use in the
listbox. Count must be an integer constant or integer variable. Using an
array that is smaller than the count value may produce unexpected results!

When the listbox is on screen, you can move up and down the list of items
using the cursor keys or the mouse. Select an item with the mouse or by
pressing Return. Cancel by pressing Undo.

    Autosearch

The listbox has a special property such that if you press a key, it will
search forward for the next item which starts with that key. This is very
useful for large lists. I recommend that you use sorted lists to benefit
most from this feature.


LTRIM$("string")

Returns string, stripped of leading 'white space' characters. 'white space'
characters include space, formfeed, newline, carriage return, tab, and
vertical tab.


MID$("string",s,n)

Returns the substring of "string" starting at location s and continuing
for n letters. n is optional. Omitting n returns the string starting from
location s. The first letter in a string is considered to start at position
1.


MOD

This is the modulus operator. It calculates the remainder obtained from an
integer division of two numbers. e.g. The result of 11 MOD 8 is 3.


NOT

Operator which performs a bitwise negation of a number.


OR

Operator which performs a bitwise OR of a number.


POPUP(n,"Title","  Item 1","  Item 2",...)

POPUP is a function call which displays a popup menu on the screen which
the user can select an item from. POPUP returns 0 if nothing was selected,
otherwise it returns the number of the item that was selected, starting
with 1 for the first item in the list.

The first value in the function call is a numeric value. If it is greater
than zero, then the corresponding menu item will be displayed with a check
mark. I sugges that you leave two leading spaces in front of each menu item
to allow room for the check mark.

The title is a string which is displayed at the top of the popup menu, in
its own box. It is always centered in the box and does not require any
leading or trailing spaces, but you can add them if you wish. The width of
the popup is always that of the widest item.

The menu items can be string variables or string array items, they do not
have to be quoted text. Popup menus are more suitable for displaying
choices than alert boxes and a lot easier to use.

    For large lists of items, use LISTBOX.

POS(0)

Returns the terminal screen cursor column location. The argument is a
dummy argument. It may seem odd that CSRLIN (with no argument at all) is
used for the cursor row and POS(0) (with a useless argument) is used for
the cursor column. Well, this is the way it's done on the IBM PC, so I
have just copied their way of doing things for compatibility.


PROMPT$(n)

This function takes up to n characters from before the current terminal
screen cursor position and returns it as a string. Doesn't go past the
beginning of the current line. Useful for getting the current prompt when
automating operations.


RIGHT$("string",n)

Returns the rightmost n letters of the string.


RND(n)

Returns a random number between 0 and 32767. If the argument is non-zero,
seeds the random number generator with that value.


RTRIM$("string")

Returns string, stripped of trailing 'white space' characters. 'white
space' characters include space, formfeed, newline, carriage return, tab,
and vertical tab.


SCREEN$(n)

Returns a line of text from terminal screen line 'linenumber'. The first
line of the screen is 1. Trailing whitespace is stripped from the line, so
a blank line is returned as an empty string "".


SET("file","section","name")
SET$("file","section","name")

Returns the value of an item in the specified profile file. SET returns a
numeric value, while SET$ returns a string. If the item does not exist,
then SET$ will return an empty string, while SET will return zero.

Current profile filenames are "STORM", "STORMKEY", "DIALDIR" and "HELP".
The ".INI" extensions are not used.


SGN(n)

Returns -1 if n is negative, +1 if n is positive.


SPACE$(n)

Returns a string of n spaces.


STR$(n)

Returns an string representation of a number n. e.g. STR$(9) returns "9".

TIME$

Returns the time as a string in the format hh:mm:ss


TIMER

Returns the time (in seconds) since the program started running. This is
actually the standard C library function clock(). Reasonably useful for
timing things.


UCASE$("string")

Returns a copy of a string converted to all uppercase characters.


ULOAD

Example:  x = ULOAD("XMODEM","FILE")

This uploads the file "FILE" using the Xmodem protocol. The 'x' will
contain the number of files actually transferred, in this case '1' if
successful, '0' if there was an error. If you omit the filename, the
protocol module will automatially put up a file selector if required by
that protocol. If you abort the transfer, the return value will be 0. If
you abort the Basic program, the file transfer will continue.

Protocol names should be the same names as listed when uploading via the
File menu. Upper and lower case are not significant. Basic will search
through the list of available protocols. If the protocol is not found, a
Basic error will result.

You can use multiple filenames, but non-batch protocols, e.g. xmodem, will
only upload the first file. Wildcards are NOT permitted in the filenames.
However, you could expand wildcards using the Basic functions FSFIRST$ and
FSNEXT$.

VAL("12345")

Converts an Ascii string into a (long) number.


WAIT(0)

WAIT(0) returns 0 if there was a timeout, otherwise it returns the string
number that was matched by the most recent WAIT statement, starting at 1
for the first string.


XOR

Performs an exclusive xor operation on two numbers.


    Reserved Basic keywords

The following Basic commands and functions are currently unimplemented but
the keywords are reserved for future expansion.

NOTE, POINT, GET, PUT, ECHO, HCOPY, HANGUP, and DIAL.